home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Mission 3
/
Mission 3.zip
/
Mission 3.iso
/
internet
/
cabdemo
/
docs
/
prog
/
modul_d.doc
< prev
next >
Wrap
Text File
|
1998-08-29
|
21KB
|
495 lines
Kurze Beschreibung der Modulschnittstelle für CAB.APP (bzw. HTML.APP).
----------------------------------------------------------------------
Updates
-------
Ab CAB 2.7 (11/1997):
- set_cookie
- get_url_cookie
- get_url_ifmod_cookie
- post_cookie
Kontakt
-------
email: aclauss@hrzpub.tu-darmstadt.de
Hinweise
--------
Das Programm CAB.APP besitzt keine Routinen um online auf das Internet
(bzw. das WWW) zuzugreifen. Der Grund ist: ich habe kein Modem und könnte
diese Routinen deshalb auch nicht testen. Über ein externes Modul
(CAB.OVL) können diese Routinen aber nachgerüstet werden.
Die Schnittstelle soll auch unter Single-TOS funktionieren, daher werden
keine speziellen Mint-Features verwendet. Sollte sie für bestimmte Module
unbrauchbar sein, bitte ich um Nachricht.
Die Schnittstelle kann an einigen Stellen noch erweitert und verbessert
werden. Sie enthält wahrscheinlich auch ein paar überflüssige Aufrufe, die
zwar in irgendwelchen Alpha-Version eines Moduls benutzt wurden, aber
jetzt höchst wahrscheinlich niemand mehr benutzen wird (z.B. begin_pexec(),
end_pexec() wurden benötigt, weil für die ersten Versuche ein ZMODEM
Programm gestartet wurde, um Daten zu übertragen).
Vorschläge zur Verbesserung bzw. Erweiterung der Modul-Schnittstelle werden
gerne entgegengenommen.
Aufruf des Moduls
-----------------
Es gibt (zur Zeit) zwei Möglichkeiten:
1) CAB.APP läd das Modul CAB.OVL mit pexec(3,...). Das Modul wird dadurch
in den Speicher geladen und reloziert, aber nicht gestartet. Nun sucht
CAB.APP nach einer 'magic number' im Speicherbereich des Moduls. Direkt
hinter dieser Zahl erwartet es die Adresse der Initialisierungs-Routine
des Moduls. Nun springt es diese Funktion an und übergibt die Adressen
zweier Strukturen. Eine dieser Strukturen enthält Funktionen, die
CAB.APP zur Verfügung stellt, und die vom Modul verwendet werden können.
Die andere Struktur muß von der Initialisierungs-Funktion des Moduls
ausgefüllt werden, diese muß dort die Adressen der Modul-Funktionen
eintragen damit sie von CAB.APP aufgerufen werden können.
Die 'magic number' ist:
0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536552
CAP.APP gibt dabei nach dem Laden des Moduls mit mshrink() den vom
Modul nicht benötigten Speicher frei.
Muss das Modul diesen mshrink() Aufruf selbst durchführen, dann muß die
'magic number' flgendermaßen lauten:
0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536572
Nachteil dieser Methode: Der Startupcode des Moduls wird nicht
ausgeführt (und deshalb sind alle Aufrufe von Funktionen die im
Startupcode initialisiert werden, nicht möglich (betrifft z.B.
printf()).
2) Als Alternative ist es auch möglich, daß ein Programm, welches die
Funktionen des Moduls bereitstellt, CAB.APP selbst nachstartet. In
diesem Fall muß CAB.APP mit dem Parameter -initfunc=<adresse> in der
Kommandozeile aufgerufen werden. <adresse> steht dabei für die Adresse
der init-Funktion (in dezimaler Darstellung, also nicht(!) Hexadezimal).
Die 'Magic Number' wird in diesem Falle nicht benötigt.
Unter Mint mit Memory-Protection muß man dann die Memory-Flags auf
GLOBAL setzen (bei beiden Programmen), da beide Programme Routinen des
jeweils anderen aufrufen.
Aufrufkonventionen
------------------
Alle Funktionsparameter müssen auf dem Stack übergeben werden. Das
Ergebnis wird im Register D0 übergeben. Variablem vom Typ 'long' sind 32
Bit breit, vom Typ 'int' 16 Bit. Bit 0 bezeichnet das niederwertigste Bit
Das bedeutet für Pure C: Alle Funktionen mit 'cdecl' deklarieren
Das bedeutet für den gcc: Die Option '-mshort' verwenden.
Beschreibung der Funktionen des Moduls
--------------------------------------
In 'modul.h' und 'init.c' (zusammengestellt von Stephane Boisson) befindet
sich schon ein Grundgerüst eines Moduls. Für Aufrufmethode 1) muß man
in main() (welches nie ausgeführt wird) einige Dummy-Aufrufe machen, damit
der Compiler nicht alle Funktionen wegoptimiert.
Das Modul CAB.OVL kann folgende Funtionen implementieren:
init_module, get_url_info, get_version, get_url
post, restore_module, mailto, get_url_if_modified
Nur zwei dieser Funktionen (init_module, get_url) müssen implementiert werden,
alle anderen sind nicht zwingend notwendig, aber für volle online-Funktions-
fähigkeit durchaus wichtig.
long init_module(url_methods_t *out, browser_info_t *in, char *path);
---------------------------------------------------------------------
Diese Funktion ruft CAB.APP direkt nach dem Start auf. In dieser Funktion
muß sich das Modul initialisieren.
'path' enthält den Pfad in dem sich das Modul befindet
(abgeschlossen durch '\').
'in' enthält alle Funktionen, die CAB-APP dem Modul zur
Verfügung stellt.
'out' In diese Struktur müssen die Adressen der Modul-
Funktionen eingetragen werden. Für Funktionen, die
nicht implementiert sind, setzt man 0L als Adresse
ein.
Als Ergebnis muß die Funktion einen Bitvektor (long) zurückliefern, indem
die vom Modul unterstützten WWW-Protokolle eingetragen wurden.
Konstanten für die Protokolle (mit 'Oder' zu veknüpfen):
SUPPORT_HTTP, SUPPORT_FTP, SUPPORT_GOPHER, SUPPORT_WAIS,
SUPPORT_MAILTO, SUPPORT_NNTP, SUPPORT_TELNET
Falls das Modul weitere Programme mit pexec(0) startet, muß man zusätzlich
noch folgendes in den Bitvektor eintragen:
SUPPORT_PEXEC
Falls die Initialisierung nicht klappt muß 0L zurück geliefert werden;
weitere Aufrufe von Modul-Funktionen finden dann nicht mehr statt.
Wichtig für Aufrufmethode 1 (siehe oben):
Die Adresse dieser Funktion muß direkt hinter der 'Magic number' irgendwo
im Programm- oder Datenbereich untergebracht werden, damit CAB.APP diese
Funktion findet und aufrufen kann (gilt nur wenn das Modul mit pexec(3)
von CAB.APP geladen wurde).
Wichtig für Aufrufmethode 2 (siehe oben):
Das Modul wird als Programm gestartet, und startet dann selbst CAB.APP,
wobei es die Adresse dieser Funktion als Parameter übergibt:
Parameter: -initfunc=<adresse>
void restore_module(void);
--------------------------
Wird aufgerufen, bevor sich CAB.APP beendet. Die Funktion sollte hier allen
angeforderten Speicher freigeben, geöffnete Datein schliessen, etc.
Diese Funktion muß nicht implementiert werden, wenn nichts dauerhaft
reserviert wurde (Dateihandles, Speicher, etc.)
void get_version(char **authorp, long *versionp, long *datep);
--------------------------------------------------------------
Erfragt Informationen über Autor, Version und Datum des Moduls. Alle
Angaben werden im 'About...' Dialog von CAB.APP angezeigt.
'authorp' Autor und Kontaktadresse. Maximal 4 Zeilen zu je 30 Zeichen.
Als Zeilentrenner bitte '|' verwenden.
'versionp' Version im BCD-Format. Oberes Wort enthält die Haupt-
versionsnummer, das untere Wort die Unterversionsnummer.
'datep' Datum im BCD-Format: 0xYYYYMMDD (Jahr, Monat, Tag)
Diese Funktion muß nicht implementiert werden.
long get_url_info(char *url, long *timep, long *sizep, char *type);
-------------------------------------------------------------------
Über das Dokument mit der URL-Adresse 'url' sollen einige Informationen
ermittelt werden. Diese Funktion wird aufgerufen um zu entscheiden, ob ein
Dokument überhaupt aus dem Internet angefordert werden muß, oder ob das
Dokument im Cache noch aktuell ist.
'url' URL-Adresse des Dokuments, über das Informationen gefordert
werden.
'timep' Hier muß das Datum (letzte Modifikation) eingetragen werden.
Im UNIX-Format: Sekunden seit 1970 (01.01.1970,00:00 => *timep=0)
'sizep' Hier soll die Länge (in bytes) des Dokuments eingetragen werden.
-1L wenn nicht feststellbar.
'type' Der Dateityp im MIME-Format. Der String-Puffer bietet Platz für
250 Zeichen. Oder Leerstring '\0', falls unbekannt.
Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.
Diese Funktion muß nicht implementiert werden. Ist für optimale Cache-
Verwaltung aber sinnvoll.
long get_url(char *url, char *filename);
----------------------------------------
Das Modul soll das Dokument mit der URL-Adresse 'url' aus dem Internet
holen und in der Datei 'filename' speichern. 'filename' enthält schon den
kompletten Zugriffspfad; Verzeichnisse müssen nicht mehr angelegt werden.
Das Dateidatum sollte korrekt auf das Datum der letzten Modifikation des
Dokuments gesetzt werden. Nur so funktioniert die Cache-Verwaltung in
Verbindung mit der 'get_url_info(..)' Funktion.
Sollte das Ziel der URL-Adresse ein Verzeichnis sein (z.B. beim ftp, gopher
Protokoll) sollte das Ergebnis als HTML-Datei abgelegt werden (falls das
nicht schon automatisch im HTML-Format ankommt???). Wenn man die
Verzeichniseinträge mit Icons versieht, kann man die folgenden eingebauten
Icons benutzen:
#define BULLET_FOLDER "<img src=\"internal-gopher-menu\">"
#define BULLET_TEXT "<img src=\"internal-gopher-text\">"
#define BULLET_IMAGE "<img src=\"internal-gopher-image\">"
#define BULLET_MOVIE "<img src=\"internal-gopher-movie\">"
#define BULLET_SOUND "<img src=\"internal-gopher-sound\">"
#define BULLET_INDEX "<img src=\"internal-gopher-index\">"
#define BULLET_BINARY "<img src=\"internal-gopher-binary\">"
#define BULLET_UNKNOW "<img src=\"internal-gopher-unknown\">"
Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.
Wird die URL-Adresse umgeleitet (Image-Maps,...) muß man dies CAB.APP
mit der Funktion 'new_url' (siehe unten) mitteilen.
long get_url_cookie(char *url, char *filename, char *cookie);
------------------------------------------------------------
Identisch zu get_url, bis auf den zusätzlichen Parameter "cookie".
In "cookie" steht die Cookie-Information für die jeweilige URL (oder 0L,
falls keine Cookie-Information vorhanden).
long post(char *url,char *content, char *enctype, char *filename);
------------------------------------------------------------------
Die Daten ('content') einer FORM-Umgebung werden mit 'POST' an 'url'
geschickt. Die Daten liegen im 'enctype' (MIME) Format vor. Zur Zeit ist
nur 'application/x-www-form-urlencoded' möglich.
Eventuell zurückgeschickte Daten sollen in 'filename' gespeichert werden.
Sollten die zurückgeschickten Datein eine neue URL-Adresse besitzen, dann
unbedingt die Funktion 'new_url' (siehe unten) benutzen.
long post_cookie(char *url,char *content, char *enctype, char *filename, char *cookie);
--------------------------------------------------------------------------------------
Identisch zu post, bis auf den zusätzlichen Parameter "cookie".
In "cookie" steht die Cookie-Information für die jeweilige URL (oder 0L, falls
keine Cookie-Information vorhanden). Wenn diese Funktion implementiert wird,
so muß auch post implementiert werden.
long mailto(char *url, char *subject, char *filename);
------------------------------------------------------
Die Datei 'filename' soll als Mail verschickt werden. 'url' bezeichnet
die Email-Adresse des Empfängers als URL, 'subject' ist der Betreff.
Als Ergebnis liefert die Funktion 0, falls alles geklappt hat, sonst -1.
long get_url_if_modified(char *url, char *filename, long *timep);
-----------------------------------------------------------------
Kombination aus get_url und get_url_info. CAB versucht zuerst mit
get_url_if_modified auf die Daten zuzugreifen, falls diese Funktion
implementiert ist. Ist diese Funktion nicht implementiert, werden
get_url und get_url_info verwendet.
CAB.OVL muss die url nur dann aus dem WWW holen und unter dem Dateinamen
filename abspeichern, wenn die Daten neuer aus timep (Unix-Format) sind.
Sind die Daten nicht neuer, sollte die Funktion ohne Fehlermeldung (d.h.
mit 0) zurückkehren. Da hier, im Gegensatz zur Funktion get_url_info(),
nicht die Länge der Daten zurückgeliefert werden kann (die Funktion kehrt
ja erst dann zurück, wenn alle Daten komplett geladen wurden), sollte die
Länge über 'msg_status(STATUS_DATALENGTH,len)' an CAB übermittelt werden.
long get_url_ifmod_cookie(char *url, char *filename, long *timep, char *cookie);
------------------------------------------------------------------------------
Identisch zu get_url_if_modified, bis auf den zusätzlichen Parameter "cookie".
In "cookie" steht die Cookie-Information für die jeweilige URL (oder 0L, falls
keine Cookie-Information vorhanden). Wenn diese Funktion implementiert wird,
so muß auch get_url_if_modified implementiert werden (beide sind aber optional).
Funktionen, die CAB.APP anbietet (browser_info_t Struktur)
----------------------------------------------------------
Das Modul kann direkt AES-Aufrufe machen, im Allgemeinen ist das aber nicht
nötig.
void (*aes_crystal)(void)
-------------------------
Für AES-Aufrufe bitte die folgenden Arrays ausfüllen und dann 'aes_crystal'
aufrufen.
int *aes_control;
int *aes_global;
int *aes_intin;
int *aes_intout;
long *aes_addrin;
long *aes_addrout;
void (*aes_messages)(int *msg)
------------------------------
Besitzt das Modul eine eigene AES-Event-Behandlung, sollte bei jedem
MU_MESAG-Event (bzw. jedem Event, welches nicht das Modul betrifft) der
Ereignis-Puffer mit dieser Funktion an CAB.APP weitergereicht werden, damit
dieses z.B. Redraws ausführen kann.
void (*msg_error)(long errno)
-----------------------------
Gibt eine Fehlermeldung aus (im Statusfenster von CAB.APP). Erlaubt sind alle
GEMDOS, BIOS und MintNet Fehlernummern.
void (*msg_status)(long no,long val)
------------------------------------
Gibt eine der folgenden Statusmeldngen aus:
no=1: 'connecting host', val unbenutzt
no=2: 'receive data', val=Anzahl der empfangenen Bytes
no=3: 'waiting for response', val unbenutzt
no=4: 'resolving host', val unbenutzt
no=5: 'sending request', val unbenutzt
no=6: 'Text formatieren...', val unbenutzt
no=7: 'Bild laden...', val unbenutzt
no=8: 'Starte Programm...', val unbenutzt
no=9: 'Formatiere Tabelle...', val unbenutzt
no=10: 'Warte auf Daten (Timeout: #)', val=Timeout
no=11: 'Konvertiere Bild...', val unbenutzt
no=12345 val=Länge der Daten
Hiermit kann das OVL jederzeit die Länge der zu übertragenden
Daten an CAB übermitteln. Dies ist insbesondere dann wichtig,
wenn get_url_if_modified aufgerufen wurde, da CAB hier nicht
die Länge der Daten zurückgeliefert bekommt.
Weitere Meldungen können bei Bedarf aufgenommen werden. Nummern bitte mit
mir absprechen.
long (*aes_events)(long msec)
-----------------------------
Mit dieser Funktion gibt man CAB.APP die Gelegenheit auf AES-Ereignisse zu
reagieren. CAB.APP ruft evnt_multi(MU_MESAG|MU_TIMER|MU_KEYBD,..) auf,
wobei 'msec' als Zeit für das Timer-Event benutzt wird. Mit einem kleinen
Wert für 'msec' kehrt die Funktion also schnell wieder zurück. CAB.APP ver-
arbeitet zunächst alle eigenen Events (z.B. Redraw, Fenster verschieben,..)
und prüft, ob der Benutzer die Aktion abbrechen will. Als Ergebnis liefert
die Funktion:
0 -> kein MU_MESAG-Event. Weitermachen.
-1 -> Aktion abbrechen (Benutzer hat ESC gedrückt).
alles andere -> Pointer auf ein GEM-Message-Array (int msg[8]) mit den
Daten des aktuellen MU_MESAG-Ereignises.
long (*alert_box)(long button,long msg)
---------------------------------------
Eine Alertbox wird dargestellt. 'button' ist der Default-Button und 'msg'
die Nummer eines Textes. Die Funktion liefert 0, wenn ein Fehler auftrat
(falsche msg Nummer), sonst den ausgewählten Button.
Mögliche Texte (msg):
msg=0 : "[2][Aktion abbrechen?][Ja|Nein]"
msg=1 : "[1][Transaktion war erfolgreich][Abbruch]"
msg=2 : "[1][Transaktion war nicht|erfolgreich][Abbruch]"
Weitere Texte können bei Bedarf aufgenommen werden. Nummer bitte mit mir
absprechen.
void (*begin_pexec)(void) void (*end_pexec)(void)
----------------------------------------------------
Mit diesen beiden Funktionen muß das Starten eines Programmes durch pexec(0)
geklammert werden. CAB.APP wird sich unter Single-TOS beim AES korrekt ab-
und danach wieder anmelden.
int (*clear_cache)(long size)
-----------------------------
Sorgt dafür, daß mindestens 'size' Bytes im Cache frei sind. Gegebenenfalls
werden einige Dateien (auf die am längsten nicht mehr zugegriffen wurde)
aus dem Cache entfernt. Konnte soviel Platz geschaffen werden, liefert die
Funktion 0 sonst -1.
size=0 bedeutet, daß der komplette Cache gelöscht wird.
int (*new_url)(char *url,char **file)
-------------------------------------
Wenn eine Dokument-Anfrage auf eine neue URL-Adresse umgeleitet wird (z.B.
Imagemaps, cgi-Scripts), muß man dies dem Hautprogramm mit dieser Funktion
mitteilen. Es ermittelt dann einen neuen Dateinamen 'file', unter dem die
Daten dann abgespeichert werden müssen. Liefert die Funktion als Ergebnis 0
soll das Dokument jetzt endgültig geholt werden, liefert sie als Ergebnis
-1, dann muß das Dokument nicht mehr geholt werden, da es sich schon im
Cache befindet.
int (*ask_user)(long msg,char **answer)
---------------------------------------
Wenn der Benutzter bestimmte Angaben machen muß, bevor fortgefahren werden
kann (z.B. bei geschützten Dokumenten mit Passwortabfrage), kann man diese
Angaben hiermit anfordern.
'msg' ist die Nummer des Textes, der angezeigt wird, 'answer' ist der
String, der vom Benutzer eingegeben wurde. Das Resultat ist 1 wenn der
Benutzter OK gedrückt hat, 0 für Abbruch und -1 bei einem Fehler (falsche
'msg'-Nummer). Der String 'answer' wird beim nächsten Aufruf dieser Funktion
wieder überschrieben daher, wenn nötig, umkopieren.
Möglicher Werte für 'msg':
msg=0 : Dokument geschützt, Name (bzw. Kennung) eingeben
msg=1 : Dokument geschützt, Passwort eingeben
Weitere Texte können bei Bedarf definiert werden. Bitte mit mir absprechen.
long basepage
-------------
Adresse der Modul-Basepage. Nur gültig, wenn Modul mit pexec(3) gestartet
wurde.
int *reloadflag
---------------
Zeiger auf ein integer. Der Integerwert ist 1, wenn der Benutzer 'Neu laden'
(Reload) ausgewählt hat, sonst 0. Kann dazu verwendet werden, eventuell gecachete
Informationen/Daten zu benutzen oder nicht.
long version
------------
Versionsnummer von CAB im ASCII format. Beispiel: V1.30 wäre 0x30313330.
proxy_url *proxy
----------------
Zeiger auf die folgende Struktur:
struct {
char *ftp_proxy;
char *http_proxy;
char *wais_proxy;
char *gopher_proxy;
char *news_proxy;
char *no_proxy;
char *smtp_server;
char *nntp_server;
} proxy_url
Das OVL sollte diese Struktur innerhalb der init-Funktion mit
Default-Werten ausfuellen. CAB hat fuer jeden String schon Speicher
(126 Bytes) reserviert. CAB wird diese Einträge ändern, falls der
Benutzter neue Einträge in CAB bestimmt. Das OVL sollte deshalb
vor dem Download der Daten diese Einträge erneut inspizieren.
void online(int state)
----------------------
Sollte vom OVL immer dann aufgerufen werden, wenn die Internet-
verbindung aufgebaut bzw. abgebrochen wird. Besteht die Verbindung
muß state=1 sonst state=0 übergeben werden. Diese Funktion darf
ab CAB-Version 1.41 aufgerufen werden (d.h.: version>=0x30313431).
Wird diese Funktion vom OVL nicht aufgerufen, geht CAB davon aus,
daß die Internetverbindung besteht. Sinnvoll einsetzbar ist die
Funktion allerdings erst, wenn das CAB.OVL in einem eigenen Thread
Änderungen des Online-Statuses überprüft, da das OVL von CAB nur
bei Bedarf aufgerufen wird.
void set_cookie(char *url, char *name, char *value, char *expires,
char *path, char *domain, int secure)
-----------------------------------------------------------------
Hiermit kann das OVL einen "Cookie", der aus der HTTP-Antwort
extrahiert wurde, setzen. Je nach getätigten Einstellungen wird CAB
den Cookie in die Cookie-Datenbank einfügen, den Benutzer fragen,
oder den Cookie ignorieren.
url - ist die URL des Dokuments, für das der Cookie geliefert wurde.
name - Name des Cookies
value - Wert des Cookies (oder 0, falls kein Wert gesetzt)
expires - Verfallsdatum (oder 0, falls nicht gesetzt) als String im
Format "Wdy, DD-Mon-YYYY HH:MM:SS GMT"
path - Zugriffspfad, für den der Cookie gültig ist.
domain - Domain, für den der Cookie gültig ist
secure - 0 für die normale (unsichere) Übertragung, 1 für sicheres HTTPS.
Diese Funktion ist verfügbar seit CAB 2.7 (d.h. Version>=0x30323730)
und(!) wenn derentsprechende Eintrag in der Struktur nicht 0L ist.